---
id: index
title: 原子化 CSS 专题导览
description: 从历史演进到 Tailwind 实战与 AI 友好工作流的技术分享索引
sidebar_position: 1
---

import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'

## 为什么读这份专题

- 原子化 CSS 是工程化的折衷：用小而精的类名替代组件级样式，降低认知和维护成本，同时配合设计 token、variants 与摇树优化。
- Tailwind 的强项在生态：JIT、variants、插件、`tailwind-merge`/`clsx`/`cva`/`tailwind-variants` 组合，以及可直接复用的社区资产（预设、主题、UI 套件）。
- 它不是银弹：缺少约束时会 class 爆炸、可读性差、设计漂移。本专题会给出「少走弯路」的做法。
- AI 友好：原子类是可组合的语料，配合提示模板和 lint/merge 校验，可以让模型安全地产出 UI，并且可被人类审阅。

## 你会获得什么

- 历史与生态：从 Raw CSS → 预处理器 → CSS-in-JS → Utility-first 的关键转折，以及组件库从 Element/AntD 走向 Headless UI/shadcn/ui/reka-ui。
- 方法论：Tailwind 设计理念、与 UnoCSS 的取舍、`tailwind-merge`、`cva`、`tailwind-variants` 的封装策略。
- 最佳实践：设计 token、`data-*` 驱动的 variants、`group/peer/aria` 组合、性能/体积验证、代码评审清单。
- AI 友好工作流：可直接复用的提示模板、常见错误与防护、自动化校验建议。
- Demo：React（shadcn/ui 风格）与 Vue（shadcn-vue/reka-ui 风格）的小型页面，含主题切换、响应式卡片、表单/数据块示例，可作为「让 AI 续写」的基准。

{/* ## 快速命令与讲稿提纲

- 安装依赖：`pnpm install`
- 运行 React Demo：`pnpm --filter react-app dev`；运行 Vue Demo：`pnpm --filter vue-app dev`
- 构建文档：`pnpm --filter website build`（或 `pnpm build:docs` 若存在别名）
- 若需拍照/截图：在对应页面保留 `<!-- screenshot: tailwindcss-{section} -->` 占位

参考提纲（45-60 分钟）：
- 开场（5m）：样式方案为何不断演进，展示时间轴与组件库演进。
- 原子化价值/风险（10m）：解决/未解决的问题 + 不适用场景。
- Tailwind 设计（10m）：JIT、variants、分层、插件与 `tailwind-merge`。UnoCSS 取舍。
- 最佳实践（10m）：tokens、`cva`/`tv`、关系类、性能/体积验证。
- AI 友好（10m）：提示模板、校验链，React/Vue 代码演示。
- Demo & Q&A（10-15m）：React/Vue 实机运行与对照代码。 */}

> 阅读顺序建议：如果你正在做迁移或评审代码，先看「最佳实践」；如果你要说服团队或输出分享，先看「历史与演进」「设计理念与对比」。

## 导航

1. [历史与组件库演进](tailwindcss/history)
2. [Tailwind 设计理念与对比](tailwindcss/tailwind-core)
3. [原子化 CSS 最佳实践](tailwindcss/best-practices)
4. [样式隔离方案与原理](tailwindcss/style-isolation)
5. [AI 友好提示与 Demo 运行指南](tailwindcss/ai-friendly-and-demos)
6. [各样式方案 Demo 与产物对照](tailwindcss/demos)

## React/Vue 代码快速预览

<Tabs>
  <TabItem value="react" label="React (shadcn/ui 风格)">

```tsx
import { Button } from '@/components/ui/button'
import { cn } from '@/lib/utils'

export function Hero() {
  return (
    <div className="grid gap-4 rounded-2xl border bg-card/80 p-6 shadow-sm md:grid-cols-2">
      <div className="space-y-3">
        <p className="text-xs uppercase tracking-[0.2em] text-muted-foreground">Atomic CSS</p>
        <h1 className="text-2xl font-semibold">让设计系统与类名对齐</h1>
        <p className="text-sm text-muted-foreground">`cva`/`tailwind-variants` 集中声明 variants，`tailwind-merge` 兜底合并，搭配 tokens 保持一致。</p>
        <div className="flex gap-2">
          <Button>开始体验</Button>
          <Button variant="secondary" className={cn('gap-1')}>
            预览代码
          </Button>
        </div>
      </div>
      <div className="rounded-xl border bg-muted/60 p-4 text-xs leading-relaxed">
        <pre className="whitespace-pre-wrap">
{`const button = cva('inline-flex items-center px-4 py-2', {
  variants: { intent: { primary: 'bg-primary text-primary-foreground', ghost: 'hover:bg-accent' } },
  compoundVariants: [{ intent: 'primary', size: 'lg', class: 'shadow-lg' }],
})`}
        </pre>
      </div>
    </div>
  )
}
```

  </TabItem>
  <TabItem value="vue" label="Vue (shadcn-vue/reka-ui 风格)">

```html
<script setup lang="ts">
import { Button } from '@/components/ui/button'
</script>

<template>
  <section class="grid gap-4 rounded-2xl border bg-card/80 p-6 shadow-sm md:grid-cols-2">
    <div class="space-y-3">
      <p class="text-xs uppercase tracking-[0.2em] text-muted-foreground">Atomic CSS</p>
      <h1 class="text-2xl font-semibold">组合变体，保持一致</h1>
      <p class="text-sm text-muted-foreground">用 `cva` 或 `tailwind-variants` 宣告变体，再用 `cn`/`twMerge` 兜底。</p>
      <div class="flex gap-2">
        <Button>开始体验</Button>
        <Button variant="secondary" class="gap-1">预览代码</Button>
      </div>
    </div>
    <div class="rounded-xl border bg-muted/60 p-4 text-xs leading-relaxed">
      <pre class="whitespace-pre-wrap">buttonVariants({ intent: 'primary', size: 'lg' })</pre>
    </div>
  </section>
</template>
```

  </TabItem>
</Tabs>
